%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This is the user's guide to FUDGIT 2.33
% Martin-D. Lacasse <isaac@physics.mcgill.ca>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% European users should probably include a4 before compiling
% The twoside option makes it appropriate for double side printing
% If you remove it, you should adjust the right and left margin
% accordingly.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentstyle[twoside,toc_entry]{report}
\adjustreport
\setlength{\oddsidemargin}{0.25in}
\setlength{\evensidemargin}{-0.25in}
\setlength{\topmargin}{-0.50in}
\setlength{\textwidth}{6.5in}
\setlength{\textheight}{8.75in}
\setlength{\headsep}{0.50in}
%\setlength{\parskip}{2pt}

\def\bq{\nopagebreak\begin{quote}\tt \setlength{\partopsep}{0pt} \setlength{\topsep}{0pt}}
\def\eq{\end{quote}}
\def\fudgit{{\sc fudgit}}
\def\readline{{\sc readline}}
\def\gnuplot{{\sc gnuplot}}
\def\sgiplot{{\sc sgiplot}}
\def\emacs{{\sc emacs}}
\def\unix{{\sc unix}}
\def\hoc{{\sc hoc}}
\def\optio{$_{\mbox{\it \footnotesize optional}}$}
\def\Seealso{{\bf See also:}}
\def\Examples{{\bf Examples:}}
\def\Example{{\bf Example:}}
\def\Syntax{{\bf Syntax:}}
\def\dash{--}

\pagestyle{empty}
\begin{document}
\vspace*{0.8in}
\begin{center}
{\Huge\bf FUDGIT}
\end{center}
%\vspace{0.1in}
\begin{center}
{\large A Multi-Purpose\smallskip\\
Data-Processing\smallskip\\
and\smallskip\\
Fitting Program}
\end{center}
\vspace{1.0in}
\begin{center}
{\Large User's Manual\\}
%{\large \it (PRELIMINARY COPY)}
\end{center}
\vspace{1.8in}
\begin{center}
Version 2.33\\
May 1993\\
\end{center}
\vspace{0.2in}
\begin{center}
Martin-Daniel Lacasse\\
Center for the Physics of Materials\\
and\\
Department of Physics\\
McGill University \\
Montr\'eal, Qu\'ebec, Canada\\
$<$isaac@physics.mcgill.ca$>$
\end{center}
\vspace{0.2in}
\begin{center}
{\normalsize \copyright\ Martin-Daniel Lacasse, 1993}
\end{center}
\cleardoublepage
\pagestyle{headings}
\pagenumbering{roman}
\renewcommand{\baselinestretch}{1}\small\normalsize
\tableofcontents
%\renewcommand{\baselinestretch}{1.5}\small\normalsize
\cleardoublepage
\chapter{Introduction}
\pagenumbering{arabic}
\section{What is \fudgit\ ?}

No more {\em fudging\/}!
Despite its name,
\fudgit\ is a double-precision multi-purpose fitting program.
It can manipulate complete columns of numbers using
vector arithmetic. \fudgit\ is also an expression language
interpreter understanding most of C grammar.
It supports most functions from the C math library.
Finally, \fudgit\ is a front end for any plotting program
supporting commands from stdin. It is a nice mathematical complement
to \gnuplot, for example.

The main features of \fudgit\ are:\\
    $\bullet$ Command shell including history;\\
    $\bullet$ Possible abbreviation of all the {\em fitting mode} commands;\\
    $\bullet$ Possible plural when it makes sense too;\\
    $\bullet$ User-definable macros;\\
    $\bullet$ Aliases;\\
    $\bullet$ Shell flow control statements such as if, else, while, foreach;\\
    $\bullet$ On-line help;\\
    $\bullet$ On-line selectable plotting program;\\
    $\bullet$ Fourier transforms;\\
    $\bullet$ Cubic spline interpolation;\\
    $\bullet$ Double-precision built-in calculator;\\
    $\bullet$ Built-in interpreter supporting most of C language including flow
    control (if, else, while, for, break, continue);\\
    $\bullet$ User-definable functions and procedures;\\
    $\bullet$ User-defined objects dynamically linkable as
    functions or procedures;\\
    $\bullet$ Double-precision vector arithmetic;\\
    $\bullet$ Access to the complete C math library;\\
    $\bullet$ Built-in fitting series such as:\\
        + power series (polynomial);\\
        + sine series;\\
        + cosine series;\\
        + Legendre polynomials;\\
        + series of Gaussians;\\
        + series of exponentials;\\
    $\bullet$ User-definable fitting functions;\\
    $\bullet$ Totally dynamical allocation of variables and parameters;\\
    $\bullet$ Possible selection of fitting ranges.

 \fudgit\ has a collection of fitting routines including:\\
    $\bullet$ straight line (linear) least squares;\\
    $\bullet$ straight line (linear) least absolute deviation;\\
    $\bullet$ general linear least squares using QR decomposition;\\
    $\bullet$ general linear least squares using singular value decomposition;\\
    $\bullet$ nonlinear Marquardt-Levenberg method.

\section{Future}
    \fudgit\ can be easily enlarged to include other built-in
    univariable manipulations such as fancy integration,
    derivative, statistics, etc. However, dynamical linking allows
    the user a lot of flexibility. Dynamical linking should be
    ported to other vendors.

    If anyone is interested in going in this direction then be my guest,
    or send me the routines you want to see included! The interpreter
    is built so that the inclusion of extra modules is fairly
    straightforward.

    On the other hand, the dynamical loader should allow
    \fudgit\ to become a nice interface
    between the user, the data files, and mathematical routines.
    An implementation of matrix arithmetic would however be required.
    This might happen one day, if time permits\ldots Users would then
    only have to build (by constructing and/or gathering routines)
    a tool box that would be totally configurable and reusable.
    \fudgit\ would then be stripped from spline/fitting/fft/etc. routines
    which would come in a separate tool box. Anyone interested?

\section{Supported Architectures}
    As it stands now, \fudgit\ can be compiled on AIX, DATA GENERAL,
    HPUX, linux, IRIX, NeXT, OSF, SUNOS, and ULTRIX. Ports can be
    easily made to other vendors. As it stands, the dynamic loading
    feature only compiles on IRIX, ULTRIX (vax only), and SUNOS. Ports
    of dynamic loading to HPUX and AIX are not foreseen in a near
    future unless someone indicates me how to implement dynamic loading
    on these operating systems. If you know something about this let me
    know. Dynamic loading should be part of new operating systems in a
    near future: stay tuned.

\section{Bugs}
    There are probably too many to enumerate. However, the program was
    fairly stable on a lot of testing and routine applications.
    Be careful with possible circular aliases; busting a vector
    by unlocking {\tt data}. Also, some malloc() libraries are
    not always happy when they work a lot.
    As with most interpreters (e.g. csh), {\tt if, else, endif}
    statements can be difficult to debug and are not much flexible.
    However, \fudgit's flow control error messages are more indicative
    than the one from {\it csh} and {\it sh}.

    The program has been written with robustness in mind and not
    optimization. Some parts of the code could therefore be improved
    for speed, but a deliberate choice has been made on robustness.
    (As an example, the default behavior is to have
    all divisions checked for a null quotient.)

    Character by character terminal mode (cbreak) is not available
    through the plotting program pipe. A (less portable) pseudo
    terminal could be used for the plotting program.

    The stack and machine could probably be allocated dynamically.
    However, recursive loops would make the program to be killed
    by init for envading the swap space.

    Redefined functions do not free the part they were previously
    occupying on the machine space, but this memory leak is not
    significant over a normal session.

\section{Credits}

\input{credits.tex}

\chapter{Tutorial}
The following sections will deal with several applications of \fudgit.
The main strength of \fudgit\ re\-sides in its capacity of fitting
and splitting multiple files. This kind of applications cannot be
done by a mouse driven program since 
commands can rarely be automated in such programs.
\fudgit\ allows the user to build scripts which can automate
a process that performs the available functions or user-defined functions
or macros over several data files. The syntax is very close to C-shell and
most of C-shell users will only have to intuitively apply their knowledge
to the current fitting mode shell. Parallel to this shell
is a built-in calculator which in
fact is a basic C interpreter supporting most of the C math library,
plus some additional features.
The particularity of \fudgit\ comes from the fact
that global variables are common to both the C-calculator
and the command shell.
Once again, a minimum knowledge
of C will suffice to write short programs using the C-calculator.

To make a rough picture, one can say that \fudgit\ uses C-shell
syntax to deal with files, C syntax to deal with vectors, numbers
and strings, and the language of your favorite plotting program for
plotting.

\section{Prerequisite Knowledge}
    To read this manual, the reader should have a minimal
    knowledge of C programming. Specifically, the user should
    understand the basics of {\tt if}, {\tt else}, {\tt while} and
    {\tt for} constructions. A basic knowledge of C operators 
    would also be preferable.
    
    A familiarity with \unix\ {\it csh} command would
    be helpful, particularly if you know the C-shell
    {\tt if}, {\tt while} and {\tt foreach} constructions, 
    as well as aliases, and string variable substitutions.
    Users already familiar with (and perhaps addicted to)
    {\it tcsh}- or {\it bash}-\emacs- style line editing will 
    feel at home.

    However, the novice reader should only refer to a C book
    to understand operators specific to C. All the rest of
    what should be known is fully covered by this manual.

    It is also understood that you already know the plotting program
    you are going to link to \fudgit.

\section{The Different Modes}
    \fudgit\ is composed of three different modes. These modes can
    be thought of as (1) a C-shell like interpreter linked with
    (2) a C-calculator,
    sharing the same variables in memory, and with (3) a plotting program
    of your choice. 

    Most of the time, commands of different modes will
    be interlaced as they are given on the command line.
    However, the present manual starts
    by giving a separate description
    of the different modes.
    In the reference manual, we assume that the different
    modes are well understood so that
    the commands are described without distinction,
    as they would be used, and independently of their
    originating mode.

\subsection{The Fitting Mode}    
    The C-shell like interpreter is called the {\em fitting
    mode}.
    It is the central mode and is the one from which all accesses
    to disk are done. This mode has a range of commands allowing
    the user to read vectors from or save vectors to a data file, to read a
    command script, save the command history, do the Fourier
    transform of a vector, make a linear or nonlinear least square
    fit, etc\ldots This mode also allows the user to define macros
    and aliases and to perform basic flow control over the statements.
    All the commands in the fitting mode can
    be abbreviated. It is worth mentioning that in the fitting mode,
    the command line parsing is done by analyzing words separated by
    blanks (spaces or tabs), as in an interactive csh.

\subsection{The C-calculator Mode}
    The {\em C mode} or {\em C-calculator mode} is a
    language interpreter supporting most of C grammar except
    pointers. It also supports most of the double-precision C math library.
    Thus, recognized keywords cannot
    be abbreviated, and the different tokens need not be
    separated. Most of the C operators and keywords are understood
    and a few extra operators have been added. This mode does
    essentially all the possible calculations on scalar variables and vectors.
    Recursive functions and procedures can be defined as well.
    Since all numeric variables are double precision numbers,
    C {\tt switch} constructions were not implemented.

\subsection{The Plotting Mode}
    The {\em plotting mode} is a channel talking directly to the
    plotting program of your choice. Therefore, \fudgit\ can serve
    as a front end to any plotting program able to accept input
    from stdin. This way, vectors
    can be built from the C-calculator and then plotted by your
    favorite plotting program (e.g. super mongo, irisplot, \sgiplot,
    plot, \gnuplot, etc\ldots). The default plotting program is
    \gnuplot.

\section{Changing from one Mode to Another}
    The fitting mode is the central mode from which the two other
    modes are accessed. Thus, one cannot change from the C-calculator
    mode to the plotting mode without going through the fitting mode.
    The mode changing commands are mnemonically called {\tt cmode} for
    changing to the C-calculator mode, {\tt pmode} for going to the
    plotting mode and {\tt fmode} to go back to the fitting mode
    from any of the two previous modes.
    In interactive use, typing \^{ }D is equivalent to {\tt fmode}
    and the program will return to the fitting mode.

    Each mode has a different type of parsing. The fitting mode
    analyzes the input line by breaking it in blank separated words,
    as the standard
    C shell. Commands can thus be abbreviated in this mode.
    On the other hand, the C-calculator
    mode parses the input line by breaking it
    into tokens and keywords of different types as
    does a C or FORTRAN compiler. Nothing can be
    abbreviated, but the different tokens need not be
    separated by white spaces. Finally, the plotting mode
    does no parsing at all, since the plotting program is
    responsible for analyzing the input line.

    The commands {\tt cmode} and {\tt pmode} can be followed
    by a list of commands on the same line, in which case the
    rest of the line will be parsed according to the mode the
    command refers to, and then processed in the mode
    specified. To make life easier, the {\tt let} command
    is equivalent to {\tt cmode} and anything following it
    will be passed to the C-calculator mode parser and then
    processed.
    
\section{Vectors, Parameters, Variables, Strings, and Constants}
    This section
    describes the different types of variables supported by \fudgit.
    They are {\bf vectors, variables, constants, string variables}
    and {\bf string constants}. To this list, we should
    add the last class of objects consisting of only one member:
    {\bf parameters}. Vector and parameter names consist 
    of upper case letters uniquely.
    Variable and constant names consist
    of lower case letters uniquely.
    String variable and string constant names
    consist of a mixture of upper case and lower case letters. Any number
    of digits or underscores can be part of a name: the remaining
    characters will then decide on the class of object the name describes.
    Vectors, parameters, variables and constants are all double precision
    numbers.

\subsection{Scope of Variables}
    All variables are allocated as they are introduced
    on the C-calculator mode command line. All such variables have a global
    scope so that they can be accessed from anywhere outside
    or inside functions or procedures. Automatic variables can
    be defined with the {\tt auto} keyword. The scope of such
    variables is delimited by braces as in standard C. The {\tt auto}
    definition has to be immediately after an opened brace. When
    defined inside functions or procedures, automatic variables
    cannot have a name already used by an argument or the function
    or procedure. Automatic variables are located on the
    stack and are freed when the brace matching the end of
    the scope is encountered.

\subsection{Vectors}
    \fudgit\ supports full vector arithmetic.
    This means that once a vector has
    been read, it can be modified using any of the supported math functions.
    A vector can also be created by a simple assignment or a
    {\tt while} or {\tt for} loop over its elements. Any vector
    part of an assignment will be created and allocated if it
    does not already exist. The allocation size is specified by the
    {\tt set samples} command. The default size is 4000.
    A constant called {\tt data} will be set to the number
    of elements that have been read. Obviously,
    {\tt data} will always be smaller than the sample size.
    Operations relating vectors are possible.
    In this case, a loop over the vector elements will
    be done from the first element to the {\tt data}$^{th}$
    element. The value of this constant is therefore
    crucial to all vector operations. We should go over an example.

    Suppose that vectors $X, Y, Z$ and {\it ENERGY}
    have been read from a file using
    a {\tt read} statement (described below).
    Now consider the following assignments:
    \bq let X=ln(X)\\
    let Y=sin(X+Z)\\
    let TIME=ENERGY\^{ }2\\
    let CONST=3\\
    let GAME=rand()\\
    let K/=GAME\eq
    which all are examples of a single equation relating {\tt data} equations,
    since each vector element will be assigned individually. Although
    all the elements of vector {\tt CONST} will be equal to 3, the elements
    of vector {\tt GAME} will be random numbers independently generated
    by the function {\tt rand()}.

    Vector elements can also be referenced individually using the usual
    C syntax. Thus, $A[2]$ refers to the second element of vector $A$.
    Vector operation can thus be done using {\tt for} loops
    or {\tt while} loop constructions.
    Note that unlike C, the first element of any vector is 1.

    Be careful with assignments involving a vector element and the same
    whole vector as in:
    \bq let VEC *= VEC[3] \eq
    which would multiply the vector {\tt VEC} by its third element.
    However, the value {\tt VEC[3]} will not be constant over the
    implied loop and the result will not be the one expected.
    Therefore, such assignments should be written using temporary
    variables as in:
    \bq let tmp = VEC[3]\\
    let VEC *= tmp\eq
    so that variable {\tt tmp} carries the value that {\tt VEC[3]}
    had before the assignment through the whole loop.

    Vectors can be saved, appended to a file, with the {\tt append vectors}
    and {\tt save vectors} command. They can be displayed at any time
    using the {\tt show vectors} command.

\subsection{Parameters}
    The short vector containing the fitting parameters is isolated
    in a class by itself. Parameters can be assigned globally or
    element by element. Clearly, parameters cannot be mixed with vectors
    but elements of it can. Therefore, statements like
    \bq
    set parameters FITPAR 2\\
    let FITPAR = 3\\
    let VECTOR = 3\\
    let FITPAR[2] = 3*sin(pi) * VECTOR[4] \eq
    all are examples of the possible declaration and usage of parameters.

    As with vectors, parameters can be displayed, saved, appended using
    the same range of commands {\tt append}, {\tt save}, {\tt show parameters}.

\subsection{Scalar Variables}
    Scalar variables have lower case names and are allocated as they
    are introduced on the command line. For example,
    \bq let x++\\
    let y=Y[4]\\
    let z=x*y \eq
    are all legal commands. Note that the first example increments
    variable $x$ only if it already exists. In terms of assignment,
    a vector or parameter
    element is considered as a variable. Variables can also
    be mixed with vectors such as in
    \bq let X=3\^{ }x\\
    let Y=x+Z\\
    let N=n++\\
    let Z=cos(X/a + Z[x]) \eq
    but statements as
    \bq let x=X+Z\eq
    are clearly not legal.

    Variables can be saved, appended to a file, with the {\tt append variables}
    and {\tt save variables} commands. They can be displayed at any time
    with the {\tt show variables} command.

\subsection{String Variables}
    String variables can also be created as needed. Any name consisting
    of both lower case and upper case letters will be considered as a string
    variable. Statements like
    \bq
    let String = "Hello"\\
    let Other\_String = String\\
    let String1 = "Good"\\
    let String2 = " Bye!"\\
    let String3 = String1 + String2\\
    let String4 = String1 - "od"\\
    let Input = Read()\\
    let y = scan(Read(), "\%lf")\\
    let x = (Other\_string == String)\\
    let y = (Other\_string != "What is going on? \verb+\n+")
    \eq
    are thus permitted. The only operations permitted on string
    variables are the equality operators, the addition operator, the
    subtraction operator, and to be arguments of string functions
    such as {\tt scan} function. In the previous example, $x$ and $y$
    will both be set to 1. Note that the {\tt Read} function returns a
    string.

\subsection{Constants and String Constants}
    A constant is a variable that is locked to its value. It can be used
    at the same place a variable can be except that changing its value
    will result in a parsing error.
    \fudgit\ contains 4 built-in
    scalar constants: {\tt pi} = $\pi$, {\tt e} = Neperian number $e$, and
    {\tt chi2} which contains the value of $\chi^2$ as obtained from
    the last fit. Finally, {\tt data} contains the effective size
    of all vectors.

    There are also 3 built-in
    string constants: {\tt ReadFile} holding the name of the last
    file read by the {\tt read} command, {\tt Tmp}
    holding a temporary filename consisting of
    {\it /tmp/fudgitPID}, where {\it PID} holds for
    a unique number describing the current process,
    and finally {\tt Cwd} containing the name of the
    current working directory.
    Constants and variables (either scalars or strings) can
    be transformed in one another using {\tt lock} and {\tt unlock}
    commands so that the user can build his own constants at any time.

    The linked list of all vectors, parameters,
    variables, constants, functions and procedures can be
    displayed by the {\tt show table} command.

\section{C-calculator Mode Essentials}
    The C-calculator mode is the mode dealing with the mathematical
    transformations of the variables. It has access to the C functions
    of the mathematical library such as $\sin(x), \cos(x), \tan(x),
    \ln(x), \log(x), \exp(x)$ and more fancy functions such as random
    number generators, Bessel functions of the first and second kind,
    error function, Gamma function and so on\ldots

    All operators of C are supported with the exception of pointer and
    bitwise operators.
    An extra \^{ } exponentiation operator has been implemented.

\subsection{Computational Errors}
    All mathematical functions, exponentiation operator and
    divisions are checked for error. Computational errors involve
    infinity values, not a number, out of range, and out of domain.
    The user can select what kind of checks she or he wants to have.
    The first two are values whereas the last two are error numbers
    set by the various mathematical functions.
    This is done using the {\tt set error} command. The user has
    the choice among the following checks:

    \begin{description}
    \item[Infinity] A value of that kind results from
    a division by zero or if the value resulting from
    a mathematical function cannot be represented by the computer.
    The number representation limit
    is 1.0e+308 for most 64 bits double machines. To give an idea,
    the exponential $e^{710}$ cannot be represented. Note
    that the infinity value is signed on some machines, e.g,
    $\log(0) = -\infty$.

    \item[Not a Number] This value is returned by a function called
    with an argument out of the domain, such as a negative
    number to a log() of a number smaller that 1 for acosh().
    This value is also returned when trying to divide 0 by
    itself, or the Infinity by itself.

    \item[Out of Range] This is a flag (error number) that is
    raised by the mathematical functions returning a value
    that cannot be represented by a double C type (double precision
    FORTRAN).

    \item[Out of Domain] This flag is raised whenever the argument
    is unacceptable for a given mathematical function. Typical examples
    are $x<0$ for $\log(x), \ln(x), x^{r}$ for any $r$,
    $x \not\in [-1,1]$ for acos$(x)$, asin$(x)$, etc.
\end{description}

    By setting the error to some of these, the user keeps
    control over the whole calculation. If a computational
    error occurs in a loop, the element number will be indicated
    along with the error message. The default is to have all
    error checks active.

\subsection{Flow Control}
    The C-calculator mode supports the {\tt if-else}, {\tt while},
    and {\tt for} constructions. The syntax is very similar
    to the one in C. They can be embedded one in another,
    with no other limit that the compiled code does not blow \fudgit's
    internal machine capacity.

    The basic C-calculator mode {\tt if} syntax is
    \bq
    if ({\it conditions}) \{\\
    {\it cmode-statements}\\
    \} else if ({\it conditions}) \{\\
    {\it cmode-statements}\\
    \} else \{\\
    {\it cmode-statements}\\
    \}
    \eq
    or, for single line statements, or semicolon separated list
    of statements typed on the same line, the following syntax
    \bq
    if ({\it conditions})\\
        {\it cmode-line-statement}\\
    else\\
        {\it cmode-line-statement}
    \eq
    is perfectly legal. The same C type of construction is valid for
    both {\tt for} and {\tt while}. Note that semicolons are separators and
    not terminators as they are in C. Therefore, empty statements
    are defined by empty braces {\tt \{ \}}.

\subsection{Functions and Procedures}
    \fudgit's C-calculator supports recursive functions and
    procedures.
    Therefore, more complex functions can be defined using the
    mathematical functions provided by the C library. I refer the
    reader to the {\tt func} and {\tt proc} items of the reference
    manual where some examples are given.
    These commands are only accessible in the C-calculator mode.
    Programming in \fudgit's C-calculator mode is very close to
    programming a simple mathematical application in standard C.
    All variable types can be passed as arguments.
    Scalar variables are passed by value whereas vectors and string
    variables are passed by pointer.

\subsection{Printing from C-calculator Mode}
    Variables and constants (either scalars or strings) can be displayed
    by typing their name on the command line. A printing list is a coma
    separated list of variables.
    Thus
    \bq
    cmode\\
    "values", x, y, X[3]
    \eq
    will display the values of string "values", x, y, and X[3], tab
    separated and appended with a newline,
    to the standard output. The {\tt print} command is a bit
    different. It will print the given printing
    list {\em without an appended newline} to a file selected
    by the fitting mode {\tt set output} command. The value of
    {\tt output} is {\it stdout} by default. It can be set to any
    filename or to either of the strings {\tt stdout} and {\tt stderr}.
    The following fragment of code will give an output similar
    to the ones obtained above:
    \bq
    fmode\\
    set output stdout\\
    cmode\\
    print "values", x, y, z, "\verb+\n+"\\
    fmode
    \eq

\subsection{Implicit Loops}
    All vector or parameter assignments imply a loop over the vector or
    parameter elements (the loop is from 1 to {\tt data}).
    In such case, a vector name can be used in place
    of an expression, and the relation will run over all elements,
    from one to {\tt data},
    the latter representing the effective size of vectors.
    This is also valid for user-defined functions (see {\tt func}).

\section{Plotting Mode Essentials}
    The {\em plotting mode} has no real command as such. It is 
    a pipe connected to the stdin of a plotting program of your choice.
    Note that all \${\it var-name} construction are still
    recognized and expanded as you talk to the plotting program.
    Moreover, all the interactive features of \fudgit, such as
    filename completion and command line history are still
    active. Even if you don't need all the features of \fudgit,
    it can still be used as a front end to your plotting
    program, especially if you get addicted to interactive
    command shells having filename completion and variable
    substitution mechanism.

\section{Fitting Mode Essentials}
    We shall now describe the central mode of \fudgit: the {\it fitting
    mode}.
    The fitting mode allows
    the user to define {\tt macros}, to {\tt alias} commands,
    and to have flow control statements as
    {\tt while}, {\tt foreach} loops and {\tt if, else} similar to those
    in C-shell. These features allow the user to deal with several files
    and collect information from fitting successive files and putting
    the results in a unique output file.
    This feature is essential when one has to do a fit on the results
    obtained from several other fits. This is what \fudgit\ was written for.
    All the fitting routines, FFT routines, and I/O accesses are done
    from the fitting mode. 

    This section gives a brief description of the range
    of commands and operations accessible to the fitting mode.

\subsection{Environment Variables}
    The fitting mode is sensitive
    to the following environment variables:
    \begin{description}
    \item[PAGER] This variable refers to the pager to use when displaying
    vectors of size larger than 24 of while interactively
    displaying long output.
    \item[SHELL] The value of this environment variable is used whenever
    the user opens a shell from fudgit.
    \item[HOME] Your home variable is used to translate the
    `\verb+~+' symbol and when {\tt cd} command is called without argument.
    \end{description}

    \fudgit\ also loads a file called {\it $\sim$/.fudgitrc} every
    time it starts. This is useful to configure the program according
    to your needs.

\subsection{Script Files}
    The {\tt load} command is one of the most handy command. All the
    commands are generally put in a file with the editor and
    then loaded in \fudgit\ using the {\tt load} command. Thus,
    complicated commands can be recalled and modified at will.
    In order to avoid confusion between your data files and the
    script files you write, we recommand that you use
    the {\it .ft} extension for your script files.
    
% Not implemented
%    Therefore, if a
%    filename not ending by {\it .ft} is
%    given to the {\tt load} command, then \fudgit\ will first search
%    for {\it filename.ft} and then for {\it filename} if the former
%    is not found.

\subsection{Signals}
    \fudgit\ responds to signals in a context sensitive way. This
    discussion will be restricted to signals sent from the keyboard
    in interactive mode since \fudgit\ will behave normally when in
    non-interactive mode, i.e., when
    it has been called with some input file names on the
    shell command line input.

    An {\it Interrupt} signal will be sent by the key combination
    {\tt Control} and {\tt C} what we will denote {\tt \^{ }C}.
    An {\it Interrupt} will abort any calculation or loop while
    in the fitting mode or the C-calculator mode. When in the
    plotting mode, the {\it Interrupt} signal will be sent to the
    plotting program and ignored by \fudgit. The behavior
    of the plotting program will depend from one program
    to another. In \gnuplot, the current action is interrupted
    and the program waits for new input.

    The key combination \verb+^Z+ will suspend the program in
    its current state. Even if this is done in the middle
    of an input line, \fudgit\ will remember where you were
    and redisplay the line when the program will
    be called back in foreground.
    This is done (only available in {\it csh} job control)
    by typing {\tt fg} at your {\it csh} command line input.

    In any mode, a {\it Quit} signal will force \fudgit\ to
    exit gracefully. This signal is generated by the key
    combination \verb+^\+. This way of exiting is left
    for situations where nothing else works.

\subsection{Input/Output}
    The Input/Output is done exclusively from the fitting mode. The
    commands {\tt read} and {\tt exec} read respectively
    from a file and a program
    and assign a given column to a vector. For example, the command
    \bq read file3 X:1 Y:3 \eq
    will assign the first column of file {\tt file3} to a vector
    named $X$ and the third column to a vector named $Y$. As we
    have seen before, the size
    of vectors is stored in a constant named {\tt data}.
    The only requirement
    on the data file is to have a constant number of columns
    separated by any number of blanks (space or tab).
    By default, anything following a `\#' will be ignored.
    Each call to {\tt read} or {\tt exec} will set the constant {\tt data} to
    the number of elements read in the specified vectors. The usage
    of {\tt exec} is quite similar to {\tt read}. For example,
    the following line will run program {\tt shortrun 32} which generates
    output to stdout in different columns:
    \bq exec "shortrun 32" TIME:1 ENERGY:2 \eq
    The first column is read in vector {\tt TIME} and the second in
    a vector named {\tt ENERGY}. Note that quotes are
    necessary to link {\tt shortrun 32} as one argument.
    A range of input can be specified
    using a range specifier after the column number. A range
    specifier is built with the syntax
    {\tt [\it lower-bound\tt:\it upper-bound\tt]}.
    Any bound can be replaced by the `*'
    wild card which means no bound. A range specifier can be
    put on any column while reading. Thus,
    \bq read fort.8 A:2[0:*] B:1[*:10] \eq
    will read all line elements from file {\tt fort.8} such that the
    second column is $\geq 0$ and that the first column is $\leq 10$.
    The resulting elements will be put in vectors $A$ and $B$ respectively
    only if both conditions are satisfied.
    Note from the previous example that the column ordering is not important.
    As we have seen above, vector names must uniquely consist of capital
    letters (`\_' is also legal) and digits
    in order to be recognized as such.
    A line range can also be specified using the syntax.
    {\tt \{\it lower-bound\tt:\it upper-bound\tt\}}.
    For example,
    \bq read file2 VALUE:1\{100:243\}\eq
    will read any valid line between line 100 and line 243 of
    file {\it file2}. The line range can be given to any
    variable, but the last range given will be the only one active.
    Line range can be mixed with value range like in what follows:
    \bq read fort.8 A:2[0:*] B:1[*:10]\{*:1024\} \eq
    which will do the same thing as before except that reading is now
    restricted to the first 1024 lines of the file.

    Vectors can be saved or appended to files with the {\tt save and
    append} commands. The syntax is straightforward:
    \bq save vectors X Y Z newfile\eq
    or
    \bq append vectors TIME ENERGY file.2\eq
    will save or append the specified vectors to the files specified.

\subsection{Variable Expansion}
    All the variables and constants (either scalars or strings) defined
    in C-calculator mode are available
    to the interactive fitting mode shell. The \$ operator will fully
    expand a string variable or string constant, i.e,
    by using the \${\it var-name} or \$\{{\it var-name}\}
    syntax.

    Quite similarly,
    if the variable or constant is a scalar, then the value of the variable
    will be expanded on the command line (as a string) according to a
    pre-selected format. The default
    format is ``\%.3g" which is reasonable for including in
    filenames. This format can be changed using
    the {\tt set format} command.

    In the fitting mode, expansion will not take place if
    the `\$' operator is following a `\verb+\+' or
    if is located between single quotes.

    Note that this variable expansion feature
    is available in all modes. To avoid the variable expansion
    in other modes, a `\verb+\+' has to protect the `\$'.

\subsection{Macros and Aliases}
    The user can design his own environment by defining macros
    and aliases. An alias is a command (first word of the line)
    that gets expanded and is interpreted along with the
    other words of the line. A macro is a user-defined procedure
    that requires a certain number of arguments to be used in
    a series of commands.
    The number of argument is specified in order to avoid
    run-time errors. Arguments are referred to using the
    \${\it arg-number} syntax. Macros and aliases are only
    definable in and recognized by the fitting mode.

    Aliases follow the C-shell syntax. Defining macros is a bit different
    and I refer the user to the reference manual found in the next chapter,
    where some examples are given along with the details. Keep in
    mind that macros and aliases are argument manipulation devices:
    arguments are all processed as strings whatever they represent
    (numbers, variable names, filename, etc.).

\subsection{Flow Control}
    The fitting mode supports the three following flow control
    constructions:
    \bq
    foreach \it Var-name \tt in \it Unix-commands\\
    fmode-statements\\
    \tt end\eq
    \bq
    if ({\it conditions}) then\\
    \it fmode-statements\\
    \tt else if ({\it conditions}) then\\
    \it fmode-statements\\
    \tt else\\
    \it fmode-statements\\
    \tt endif\eq
    \bq
    while ({\it conditions})\\
    \it fmode-statements\\
    \tt end\eq
    Their grammar is identical to the one in C-shell apart from the
    fact that {\tt foreach} only expands \unix\ commands, and that the
    {\it conditions} of {\tt if} and {\tt while} are C-calculator
    mode expressions. Thus the `\$' operator is not required and the
    whole set of functions of the C mathematical library is
    available to the user.

\subsection{Fourier Transforms}
    One dimensional Fourier transforms can be done directly from the
    fitting mode command line. Although fast Fourier
    transforms require a number
    of data points equal to a power of 2, the user
    can still write scripts that will pad the vectors with zeros,
    up to the nearest power of 2. Note that this process
    involves an approximation in the resulting vectors. Fourier
    transforms require the real and the imaginary part. Real Fourier
    transforms can be done simply by supplying a null imaginary
    part. The user can use the full power of the C-calculator mode
    to implement her preferred windowing functions.
    Full details of indexing can be found in the reference
    manual under items {\tt fft} and {\tt invfft}.
    
    \fudgit\ also includes a smoothing command based on a loop
    of Fourier transforms using a cut-off frequency. For more detail,
    read the description of {\tt smooth} command
    in the reference manual.

\subsection{Cubic Spline Interpolation}
    \fudgit\ allows the user to interpolate a value given a set of 
    relations $y_i = f(x_i)$. This can be useful to get an estimate
    of the integral of a relation for which only a few points were
    obtained. Interpolation consists in two steps: an initialization
    process {\tt spline} called with the two vectors characterizing
    the relation (e.g., {\tt spline X Y}), and one or
    successive calls to C-calculator mode function {\tt interp(x)}
    returning the interpolated value.

    An example is presented to make it clearer.
\nopagebreak\begin{verbatim}
     # Read functional relation
     # Say file "relfile" contains 24 data points
     # ranging from x=2 to x=12
     read relfile X:1 Y:2
     # Initialize spline routine
     spline X Y
     # Build a curve having 120 data points from this set
     set data 120
     # Build new X vector ranging [0, 1]
     let x=0; X=x++; tmp=data-1; X/=tmp
     #  Map to X ranging [2, 12]
     let X = 10*X + 2
     # Build new Y vector including original set of 24 data points
     let Y = interp(X)
\end{verbatim}

    The previous example shows a {\it natural cubic spline} for which the
    {\it second} derivative of the interpolating curve is
    such that it vanishes at the first and the last data points
    of the original set. The {\tt spline} command accepts
    optional third and fourth arguments specifying the value of
    the {\it first} derivative of the interpolating curve at,
    respectively, the first and last data points of the original set.

    See the reference manual for more details.

\subsection{Basic Statistics and Integration}
    As it stands now, \fudgit\ does not support fancy statistics.
    However, the user can write his own scripts, procedures and
    functions to deal with basic statistics. The {\tt sum} built-in
    math function provides a handy way of calculating the mean, and the
    standard deviation (and variance).
    Thus, given a vector $X$,
\nopagebreak\begin{verbatim}
    let X2 = X*X                 # define a vector containing the square of X
    let mean = sum(X)/data       # get the average
    let VAR = (X-mean)^2         # VAR contains the square of the difference
    let var = sum(VAR)/(data-1)  # the variance as such
    let sigma = sqrt(var)        # the standard deviation
\end{verbatim}

    When used in conjunction with {\tt spline} and {\tt interp},
    the {\tt sum} command can also be used to perform
    basic numerical integration.
    Given a data set $X$ representing sample points of
    a smooth function, basic numerical integration can
    be performed by applying a {\tt spline-interp} procedure
    to build a denser vector $NEWX$.
    The interpolation should be
    made such that increasing {\tt data} would not
    change the value of {\tt sum(NEWX)/data}.
    Other basic integration techniques can also
    be computed directly using the C-calculator
    programming language.
    See the reference manual for a more detailed
    description of each of the commands mentioned above.

\subsection{Fitting Commands}
        We are now ready to perform a fit. We shall go over some examples,
        slowly introducing features of \fudgit.
        In the following example, we shall fit $y=ax^b$ by using the
        log-log representation and fitting a straight line by a least-square
        method. Refer to the reference manual in the next chapter to
        understand the commands as they as introduced.
        \nopagebreak\begin{verbatim}
        # We fit a straight line
        set function straight
        # using least square linear regression
        set method ls_reg
        # with 2 parameters called, say, B[1] and B[2]
        set parameters B 2
        # Read elements having positive X and Y values from file fort.32
        read fort.32 X:1[0.00001:*] Y:2[0.00001:*] DY:4
        # Take the ln() 
        let DY /= Y
        let Y = ln(Y)
        let X = ln(X)
        # do the fit
        fit X Y DY
        # Save the result in file myfit
        save parameters myfit
        \end{verbatim}
        All these commands could be typed interactively (without the comments)
    or put into a file (with the comments)
    and then {\tt load}ed. The file could also
    be given as an argument to \fudgit\ by typing
    \bq \% fudgit scriptfile.ft \eq
    from your C-shell. Note that the extension {\it .ft} is not necessary
    but is strongly recommanded.

    In the following example, we shall fit two Gaussians using a nonlinear
    Marquardt-Levenberg method. Nonlinear fitting is generally done
    interactively since the parameter space is explored so as to minimize
    the value of $\chi^2$. Some local minima can be reached in which
    case the values of the parameters will not be representative.
    Nonlinear fitting is an art!
    \nopagebreak\begin{verbatim}
    set function gauss          # We fit two Gaussians  
    set method ml_fit           # using Marquardt-Levenberg
    set parameters VAL 6        # We need 6 parameters called, say, VAL
    read out2 T:1 E:2 ERROR:3   # Read elements from file out2
    # Nonlinear fits is an art!
    adjust 1 2 3 4 5 6  # Adjust all 6 parameters
    # Initialize some parameters, 
    # since 'set parameters' created vector VAL = 0  by default
    let VAL[1] = 1
    let VAL[2] = -10
    let VAL[3] = 3
    let VAL[4] = 8
    let VAL[5] = -2
    let VAL[6] = 0
    fit X Y DY                   # do the fit
    # You might need to use less variables in your fit
    adjust 1 5  
    # Initialize again
    let VAL[1] = 2
    .
    .
    .
    fit X Y DY
    # Are you satisfied of CHI^2?
    # show parameters to see curvature matrix and correlations
    show parameters
    # save parameters in a file along with respective errors
    save parameters myfit
    \end{verbatim}

    Finally, we shall see an example involving a user-defined function.
    This example shows how multiple fits can be appended in a file. It
    also shows the use of macros.

\nopagebreak\begin{verbatim}
    # Make a series of fits from different directories
    # Each directory bears a name representing a temperature value
    # Tell GNUPLOT to not put a key
    pmode set nokey
    # The 2-d Ising critical temperature is tc
    let tc = -1.0/(0.5*ln(sqrt(2)-1))
    # Define the central macro
    # Call this macro fitscript and it takes one argument
    macro fitscript 1
        # Save the temperature value as a variable
        let temp=$1
        # Convert it since it was in units of tc
        let tempc = temp*tc
        # Compute the Onsager surface tension for this temperature
        let s = 2 *(1+(tempc/2)*ln(tanh(1/tempc)))
        # Read the data from this specific directory
        read $1/landm.0 T:1[20:*] U:2
        # Convert vector time
        let SQT = 1/sqrt(T)
        # Fit, the function and method are defined below.
        # Don't worry: we are defining a macro first.
        fit T U DU
        # Save the transformed and fitted vectors in the same directory
        # for subsequent plotting
        save vec SQT U UFIT $1/landm.0.newfit
        # Append the fitted parameters in file common to all fits
        # as well as the temperature value in the first column
        append var temp A[1] DA[1] A[2] DA[2] A[3] DA[3] newpar.0
        # Go in plotting mode to talk to GNUPLOT directly.
        pmode 
        plot '$1/landm.0.newfit' using 1:2,\
        '$1/landm.0.newfit' using 1:3 with lines
        fmode
        # This is it!
    stop
    #
    # The real work starts here
    # We shall use a three parameter fit
    set parameter A 3
    # Marquardt-Levenberg
    set method ml_fit
    # Adjust them all
    adjust 1 2 3
    # Initialize
    let A[1] = -2
    let A[2] = 1
    let A[3] = 2
    # This is the function fitting vector U: Therefore, it must be called UFIT.
    # One can use any temporary variable (e.g. TMP) to accelerate computation
    # Note how to build names of parameter partial derivatives
    set function user
        UFIT = A[1] + s* (A[2]^2 + A[3]^2* T)^(-0.5)
        DUFITD1 = 1                        # derivative wrt A[1]
        TMP = s*(A[2]^2 + A[3]^2*T)^(-1.5) # Temp var speeds up!!!
        DUFITD2 = -A[2]*TMP                # derivative wrt A[2]
        DUFITD3 = -A[3]* T * TMP           # derivative wrt A[3]
    stop
    # Do all directories and append to the parameter file
    # 0.0001 0.10 0.20 0.30 0.40 0.50 0.60 0.70 0.80 0.90 0.95 0.97 1.00
    foreach Dir in echo 0.0001 0.[1-9]? 1.00
        echo Doing $Dir
        fitscript $Dir
    end
    \end{verbatim}
    Some more examples are given in a subsequent chapter. You should
    now be able to write your own fitting scripts. I suggest that you
    read the following items in the reference manual:
    \bq
    adjust, fit, set/show function, set/show iteration, set/show method,\\
    set/show parameters, show fit, show/save parameters\eq
    and other related topics as found in the description of these commands.

\section{Interactive Command Line Shell}
    When used interactively, the shell keeps a complete history
    of previous commands, independently of the mode.

    The shell also supports command completion and filename completion.
    In the fitting mode, 
    if the tab key is pressed while the cursor is in the first
    argument, \fudgit\ will try to expand to a known command, alias
    or macro. Therefore, pressing tab twice on an empty line
    will list all the currently active commands, macros and aliases.
    If the cursor is not located in the first argument of the line,
    then \fudgit\ will try to expand the argument
    to an existing filename or to an existing printable variable
    if a \$ is found before the alphanumeric
    string to expand. Filename
    expansion supports the `\verb+~+' HOME designator.

    While in C-calculator mode, the expansion reduces to all
    what is found in the math lookup table, including
    variables, constants, vectors, functions, procedures
    and keywords. 

    In the plotting mode, expansion reduces to filename completion
    or to printable variable completion if the alphanumeric
    string to expand starts with a `\$'.

    Lines can be continued on the next one
    by using a `\verb+\+' at the end of the line as in {\it csh}.
    Usually expanded characters can be put as is by {\it escaping}
    them with a leading `\verb+\+'.

\section{Dynamic Loading}
    Some operating systems%
    \footnote{It will become a standard for the next generation of UNiX.}
    allow to load an object (a {\it file.o})
    at run-time.%
    \footnote{While the program is running, and without recompiling it.}
    To do so, a dynamic loading (dl or dld) library, as well
    as some features of the loader {\tt ld(1)} on IRIX are required.
    The present version of \fudgit\ supports dynamic loading on IRIX,
    ULTRIX, and SUNOS only.
    However, \fudgit\ needs to be linked (at compilation time)
    by the GNU {\tt ld(1)} link editor when built on SUNOS.

    Thus, the user can load any module of his own and momentarily
    {\tt install} it in the internals of \fudgit\ as a procedure
    (not returning a value) or a function (returning a value).
    Be sure external routines are of type {\it void} for procedures
    and of type {\it double} for functions, although a cast is internally
    done.

    The {\tt install} command allows the user to choose a different
    name for the internal installation, with the only restriction
    that the name be composed of lowercase letters only (as {\tt proc}
    and {\tt func} do). Once the external functions and/or procedures
    are installed, they can be used like any internal function or procedure.

    Arguments are all passed by pointers to the external routine. Thus,
    the user have direct access to vectors, parameters, and strings passed
    as arguments. The case of variables is different however. Even if
    the value of an expression-variable is passed by pointer, the address
    is pointing to a temporary location storing the value of the expression.
    This is done so that calls like
\bq
let y = myfunc(X, sqrt(sin(x)), data)
\eq
    be possible. A full example is presented in the section of
    the reference manual describing the {\tt install} command.
    Also read the file {\it fudgit.h} located in the {\it tools}
    directory of this distribution. This file should be included
    in your modules.

    Note that although vector indices run from 1 to {\tt data} in
    the C-calculator mode, they run from 0 to {\tt data-1} when
    manipulating the same vectors from your own C modules and
    from 1 to {\tt data} when in FORTRAN. The
    pointers passed are always the address of the first element.
    
    FORTRAN functions and procedures can be loaded provided
    an underscore is appended to the function or procedure name.
    This means that if you have a subroutine called {\it mysub} in a
    compiled object called {\it fortran\_mod.o}, you
    must called {\tt install} with
\bq
install fortran\_mod.o mysub\_:myname(X, n)
\eq
    to install procedure {\tt myname()} which accepts one vector
    and one expression as arguments. All functions and procedures
    are strongly typed in \fudgit. This means that all arguments
    are checked for number and type consistency. Note that the colon
    (:) means to install {\tt mysub} as a procedure called {\tt myname}.
    Using an equal sign (=) would have installed it as a function.
    The user can install several functions and procedures from
    the same object: they would only need to be listed at the end
    of the preceding example line.

    Future versions of \fudgit\ should provide support for
    string arguments in FORTRAN modules.

    The command {\tt reinstall} is equivalent to {\tt install}
    but it is used when a module has already been loaded once
    in the course of a \fudgit\ session. {\tt reinstall} will
    first unload the module so that symbols do not get defined
    twice in the program. 

    More details and a full example will be found under the {\tt install}
    item of the next chapter.

\chapter{Reference Manual}
    This chapter describes all the supported commands. As a convention,
    any name printed in {\it italics} is a generic name. Any name printed
    in {\tt typewriter} style is a command name that has to be typed as such.
    Optional arguments are given a
    subscript\optio\ at the end of the optional string. 
    All commands are assumed to be {\em fitting mode} commands except
    when specified otherwise.

\input{reference.tex}

\chapter{More Examples}
 Here follows a few more examples that can help writing your own scripts.
 The following scripts also show how commands can be abbreviated.

\section{Example 1}
\nopagebreak\begin{verbatim}
# Example 1
# read a file and transform the first column to 1/sqrt(x) and plot
set plotting /usr/local/bin/gnuplot
pmode set term X11
macro plot 2
    save vec $1 $2 $Tmp
    pmode plot "$Tmp" with lines
stop
read landm.0 X:1 Y:2
# this line is ignored
# a line can be blanked too

let X = 1/sqrt(X)
plot X Y
# EOF
\end{verbatim}

\section{Example 2}
\nopagebreak\begin{verbatim}
# Example 2
# fit a straight line using singular value decomposition
set function poly
set parameters A 2
set method svd
read landm.0 X:1 Y:2
let X=1/sqrt(X)
let DY = 1
fit X Y DY
save vec X Y YFIT DY
\end{verbatim}

\section{Example 3}
\nopagebreak\begin{verbatim}
# Example 3
# fit a straight line using the nonlinear method (why not?)
set fun us
    YFIT = A[1] + A[2]*X
    DYFITD1 = 1
    DYFITD2 = X
stop
set met ml
set par A 2
adjust 1 2
read landm.0 X:1 Y:2
let X=1/sqrt(X)
# We have to use a weight of 1 for chi^2 if unknown...
let DY=1
let A[1] = -2
let A[2] = 1
fit X Y DY
sav par myfile
set plo /usr/local/bin/sgiplot -p
sgip X YFIT
# EOF
\end{verbatim}

\section{Example 4}
\nopagebreak\begin{verbatim}
# Example 4
# Make the Fourier transform of a sine distribution.
# Shows how padding can be done.
# Windowing can be done by multiplying your vector by a chosen
# distribution weight factor.
# Uses GNUPLOT.
macro dofft 2
    fft $1 $2 $1_FT $2_FT
    let POW$1 = $1_FT^2 + $2_FT^2
stop
macro doinvfft 2
    invfft $1 $2 $1_IFT $2_IFT
    let POW$1 = $1_IFT^2 + $2_IFT^2
stop
pmode clear; set data style line
# Use 800 points padded to 1024
set data 1024
let n=0
let N=n++
# The null imaginary part
let IM=0
let x=0
let X=x++
let X*=(2*pi/data)
# Initialize A to zero on 1024 points
let A=0
# But only fill 800 with the function
set data 800
let A=cos(2*X) + sin(2*X) + cos(20*X) + sin(20*X)
set data 1024
# Plot the function
gnu N A
pause -1 The function: Hit return
# Fourier transform
dofft A IM 
# Plot first half of transform since real
unlock data
let data/=2
gnu N POWA
pause -1 The Fourier transform: Hit return
let data*=2
lock data
# Do the inverse Fourier transform
doinvfft A_FT IM_FT
# Plot the real part which should be the original vector.
gnu N A_FT_IFT
echo The function transformed back
# EOF
\end{verbatim}

\section{Example 5}
\nopagebreak\begin{verbatim}
# Example 5
# A bunch of utilities to use with GNUPLOT.
# All plot commands are written and then loaded by gnuplot
# Written by Ross Thomson.
#
# Initialize or Reset plot number
alias reset!Plot let plot_num = 0

# A macro to do a single plot in gnuplot
macro ipl!ot  2
   resetPlot
   plot $1 $2
stop

# Plot for gnuplot with repeated plots 
macro pl!ot 2
    save vector $1 $2 $Tmp.$plot_num
    if (plot_num) then
        pmode replot "$Tmp.$plot_num"
    else 
        pmode plot "$Tmp.$plot_num"
    endif 
    let plot_num++
stop

# Plot for gnuplot with repeated plots and titles
macro tpl!ot 3
    save vector $1 $2 $Tmp.$plot_num
    if (plot_num) then
        pmode replot "$Tmp.$plot_num" title "$3"
    else 
        pmode plot "$Tmp.$plot_num" title "$3"
    endif 
    let plot_num++
stop

# Initialize variables before a batch plot
macro tbip!lot 0
    !rm -f $Tmp.gnuscript
    set output $Tmp.gnuscript
    resetPlot
stop

# Plot for gnuplot batch plots (handled by gnuplot) and titles
# Plotting instructions are only put in file and then given to gnuplot
macro tbpl!ot 3
    save vector $1 $2 $Tmp.$plot_num
    if (plot_num) then
        let print ", '$Tmp.$plot_num' title '$3'\\"
    else 
        let print "plot '$Tmp.$plot_num' title '$3'\\"
    endif 
    let plot_num++
stop

# To be called after a tbplot
macro bat!chplot 0
  let print "\n" 
  set output stdout
  pmode load "$Tmp.gnuscript"
  pmode pause 0  "Batch plotted"
stop

# Some plotting macros
# Save the current graph in a square printable postcript file
# Usage: sqpost filename.ps
macro sqpost 1
    pmode
       set size 0.7,0.92
       set term post port 'Helvetica-Bold'
       set output '$1'
       replot
       set term X11
       replot
    fmode
stop

# Save the current graph in a rectangular printable postcript file
macro post 1
    pmode
       set size 0.7,1.0
       set term post port 'Helvetica-Bold'
       set output '$1'
       replot
       set term X11
       replot
    fmode
stop
\end{verbatim}
\appendix
\chapter*{GNU Readline and History Library}
The followings are the user's guides as extracted
from the manuals of GNU \readline\ 1.1
which can be found integrally in the readline directory, along with
the copyrights. They are reproduced here for the sake of
completeness of \fudgit\ user's guide.
\newpage
\input{hsuser}
\input{rluser}

\end{document}
